fix(terminal): scroll a phone drag by finger travel, not per touchmove - #963

Problem

On a phone, a slow drag scrolls herdr's history steadily, but a quick swipe over the same distance moves only a few notches. The text does not follow the finger, and flicking through a long agent transcript takes many repeated drags.

Cause

onTouchMove in PaneTerminal.tsx dispatched one synthetic pixel-mode WheelEvent per touchmove. With mouse reporting on (herdr attach), xterm 5.5 sends exactly one wheel report per wheel event: getLinesScrolled is used only as a zero check, and its _wheelPartialScroll %= 1 drops every whole row beyond the first. The wheel-speed replay only covers trusted events, so touch got no compensation. A 40-60 px touchmove (a flick) crossed 2-3 rows but sent one report; a slow drag sent about one per row.

Fix

• New pure helper src/lib/wheelSteps.ts: wheelSteps(pixels, stepPixels) returns the whole signed steps and the pixels left over. HERDR_MOUSE_SCROLL_LINES = 3 is herdr's default ui.mouse_scroll_lines.
• The touch handler gathers the gesture's travel (touchPixels, reset on touchstart), divides it by cell height x 3, and dispatches that many DOM_DELTA_LINE wheels of deltaY +-1 (each makes xterm send exactly one report), keeping the rest for the next move. One report then moves herdr about as far as the finger moved.
• The selecting drag's wheel (dragWheel) uses the same helper and the same cellHeight() so the two conversions cannot drift.
• src/AGENTS.md geometry row updated.

No momentum in this PR: a flick still stops where the finger lifts (onTouchEnd sends at most one leftover step, see the merge-session review below). render-scroll-2 also proposed a decaying momentum phase; that is deferred to a follow-up and this PR closes only the per-touchmove report loss.

Tests

• scripts/terminal-pinch-regression.ts (browser, runs in ui-contexts-regression): at the 13 px baseline it drags 300 px once in 2 touchmoves and once in 30, and asserts both send the same wheel count (about 300 / (3 x cell height)) and that every wheel is DOM_DELTA_LINE. Verified to fail on main's PaneTerminal.tsx ("a 2-move swipe sends line-mode wheels only"). The finger left after a partial pinch release now moves three wheel steps of the 20 px cell (it moved 60 px, under one step, so that negative check could not fail).
• src/lib/wheelSteps.test.ts (new): five 60 px moves send the same report count as thirty 10 px moves (and 300 x 1 px equals one 300 px move); sign and remainder carry; a reversal pays back gathered travel first; a zero/NaN cell height makes no steps.
• bun run typecheck: pass. bun run test:unit: 0 fail.
• bun run build, then bun run check run bun scripts/ui-contexts-regression.ts: pass, including checkTerminalPinch (earlier commit); after the test update, bun run check run bun scripts/terminal-pinch-regression.ts: pass. Its one-finger drag went from 60 px to 150 px: at a 20 px font, 60 px is less than one three-row step, so it would no longer send a wheel. That script only asserts that synthetic wheel events are dispatched; it does not check how far herdr scrolls.
• scripts/windows-lens-browser-qa.ts (manual QA, not a CI lane) is the only script that drags a finger into real herdr history. It failed twice at an earlier step ("the command's output reaches the mirrored terminal", in the mirror-only part), before the touch-scroll step ran. So the herdr-side scroll distance was not verified end to end here.

Notes

• The browser cannot read the PC's herdr config. On a PC where mouse_scroll_lines was changed, one step scrolls that many lines instead of 3, so the text moves proportionally faster or slower than the finger.
• terminalWheelSpeed still does not apply to touch (unchanged: the replay is for trusted wheels only).
• A slow drag now sends about a third of the reports it sent before. Before, it scrolled about 3 lines per row of finger travel; now it scrolls about 1.
• Overlap: feat(appearance): add a phone-only terminal scrollbar toggle #945 (phone terminal scrollbar) does not touch the drag translation. feat(terminal): hide the on-screen keyboard, with built-in Korean input #946 and feat(chat): port t3code chat rendering, composer and settings features #951 edit PaneTerminal.tsx elsewhere: textual merge-conflict risk only, no semantic overlap.
• Source: mobile-terminal stability audit, finding render-scroll-2.

🤖 Generated with Claude Code

Merge-session review

Fixed (b462b57):

• Short drags no longer get lost. Before this, a one-finger flick shorter than one step (3 rows, so 51 px at the default 13 px font) sent no wheel at all, and every longer drag dropped its last partial step. Now, on touchend of a one-finger drag (not a pinch, not an adopted grid, not a touchcancel), one more line-mode wheel is sent if at least half a step is left (finalStep in src/lib/wheelSteps.ts). Unit cases cover finalStep. scripts/terminal-pinch-regression.ts now checks that a 0.7-step flick sends exactly one wheel and a 0.3-step flick sends none. On the previous head this case failed: "a flick of 0.7 step (40 px) sends one wheel". The changelog fragment and the src/AGENTS.md row now describe the touchend step.

Deferred:

• Momentum/inertia scrolling after a fling (already listed above). This is still out of scope.

Checks: bun run check fast passes, and CI=1 bun run check run --build bun scripts/terminal-pinch-regression.ts passes.